{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Trace Buffer - Tracing IIC Transactions\n",
    "The Trace_Buffer class can monitor the waveform and transations on PMODA, PMODB, and ARDUINO connectors.\n",
    "\n",
    "This demo shows how to use this class to track IIC transactions. For this demo, users have to connect the Pmod TMP2 sensor to PMODA."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 1: Overlay Management\n",
    "Users have to import all the necessary classes. Make sure to use the right bitstream."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from pprint import pprint\n",
    "from time import sleep\n",
    "from pynq import PL\n",
    "from pynq import Overlay\n",
    "from pynq.drivers import Trace_Buffer\n",
    "from pynq.iop import Pmod_TMP2\n",
    "from pynq.iop import PMODA\n",
    "from pynq.iop import PMODB\n",
    "from pynq.iop import ARDUINO\n",
    "\n",
    "ol = Overlay(\"base.bit\")\n",
    "ol.download()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Instantiating Temperature Sensor\n",
    "Although this demo can also be done on PMODB, we use PMODA in this demo.\n",
    "\n",
    "Set the log interval to be 1ms. This means the IO Processor (IOP) will read temperature values every 1ms."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "tmp2 = Pmod_TMP2(PMODA)\n",
    "tmp2.set_log_interval_ms(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Tracking Transactions\n",
    "Instantiating the trace buffer with IIC protocol. The sample rate is set to 1MHz. Although the IIC clock is only 100kHz, we still have to use higher sample rate to keep track of IIC control signals from IOP.\n",
    "\n",
    "After starting the trace buffer DMA, also start to issue IIC reads for 1 second. Then stop the trace buffer DMA.\n",
    "\n",
    "Users can also use the following code for initialization when no decoder is available:\n",
    "```python\n",
    "tr_buf = Trace_Buffer(PMODA,pins=[2,3],protocol=\"i2c\",rate=1000000)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "tr_buf = Trace_Buffer(PMODA,pins=[2,3],probes=['SCL','SDA'],\n",
    "                      protocol=\"i2c\",rate=1000000)\n",
    "\n",
    "# Start the trace buffer\n",
    "tr_buf.start()\n",
    "\n",
    "# Issue reads for 1 second\n",
    "tmp2.start_log()\n",
    "sleep(1)\n",
    "tmp2_log = tmp2.get_log()\n",
    "\n",
    "# Stop the trace buffer\n",
    "tr_buf.stop()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Parsing and Decoding Transactions\n",
    "The trace buffer object is able to parse the transactions into a `*.csv` file (saved into the same folder as this script).\n",
    "    \n",
    "Then the trace buffer object can also decode the transactions using the open-source `sigrok` decoders. The decoded file (`*.pd`) is saved into the same folder as this script.\n",
    "\n",
    "Users will not be able to use the `decode()` function when no decoder is available. In that case, just delete the last line in the following cell.\n",
    "\n",
    "Reference:\n",
    "https://sigrok.org/wiki/Main_Page"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Set up samples\n",
    "start = 500\n",
    "stop = 3500\n",
    "\n",
    "# Parsing and decoding samples\n",
    "tr_buf.parse(\"i2c_trace.csv\",start,stop)\n",
    "tr_buf.decode(\"i2c_trace.pd\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 5: Displaying the Result\n",
    "\n",
    "The final waveform and decoded transactions are shown using the open-source `wavedrom` library. All the parsed and decoded samples will be displayed.\n",
    "\n",
    "**Note**: It may take a while for the waveforms to be displayed.\n",
    "\n",
    "Reference:\n",
    "https://www.npmjs.com/package/wavedrom"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<script type=\"WaveDrom\">{\"signal\": [{\"data\": [\"Start\", \"Address read: 4B\", \"ACK\", \"Data read: 10\", \"ACK\", \"Data read: 78\", \"NACK\", \"Stop\", \"Start\", \"Address read: 4B\", \"ACK\", \"Data read: 10\", \"ACK\", \"Data read: 78\", \"NACK\", \"Stop\", \"Start\", \"Address read: 4B\", \"ACK\", \"Data read: 10\", \"ACK\", \"Data read: 78\", \"NACK\", \"Stop\", \"Start\", \"Address read: 4B\", \"ACK\", \"Data read: 10\", \"ACK\", \"Data read: 78\", \"NACK\", \"Stop\"], \"wave\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4xxxxxxxxx4.......................................................................xxxxxxxxxxx4.........4..................................................................................4.........x4...................................................................................4.........xxxxx4x4xxxxxxxx4........................................................................xxxxxxxxxxx4.........4...................................................................................4.........4.................................................................................x4.........xxxxxx4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx4xxxxxxxxx4........................................................................xxxxxxxxxx4.........x4...................................................................................4.........4.................................................................................x4.........xxxxxx44xxxxxxxxx4........................................................................xxxxxxxxxx4..........4.................................................................................x4.........4..................................................................................4.........xxxxxx4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\", \"name\": \"\"}, {\"data\": [], \"wave\": \"1.................................................................................................................................0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1...........0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1.............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1.....0....1....0....1....0.....1....0....1...........0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1....0....1....0.....1....0....1....0....1....0.....1.......................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................\", \"name\": \"SCL\"}, {\"data\": [], \"wave\": \"1.............................................................................................................................0....1.........0....................1.........0..........1..............................0.........................................1.........0.............................................................1.........................................0..............................1..........0.........1.0...1.........0.....................1.........0.........1..............................0.........................................1.........0..............................................................1........................................0...............................1.........0..........1..................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................0....1.........0.....................1.........0.........1..............................0.........................................1.........0..............................................................1........................................0...............................1.........0..........10....1.........0....................1.........0..........1..............................0.........................................1.........0..............................................................1........................................0...............................1.........0.........1..................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................\", \"name\": \"SDA\"}], \"head\": {\"text\": [\"tspan\", {\"class\": \"info h4\"}, \"Protocol decoder: i2c; Sample rate: 1000000 samples/s\"], \"tock\": \"0          10          20          30          40          50          60          70          80          90          100          110          120          130          140          150          160          170          180          190          200          210          220          230          240          250          260          270          280          290          300          310          320          330          340          350          360          370          380          390          400          410          420          430          440          450          460          470          480          490          500          510          520          530          540          550          560          570          580          590          600          610          620          630          640          650          660          670          680          690          700          710          720          730          740          750          760          770          780          790          800          810          820          830          840          850          860          870          880          890          900          910          920          930          940          950          960          970          980          990          1000          1010          1020          1030          1040          1050          1060          1070          1080          1090          1100          1110          1120          1130          1140          1150          1160          1170          1180          1190          1200          1210          1220          1230          1240          1250          1260          1270          1280          1290          1300          1310          1320          1330          1340          1350          1360          1370          1380          1390          1400          1410          1420          1430          1440          1450          1460          1470          1480          1490          1500          1510          1520          1530          1540          1550          1560          1570          1580          1590          1600          1610          1620          1630          1640          1650          1660          1670          1680          1690          1700          1710          1720          1730          1740          1750          1760          1770          1780          1790          1800          1810          1820          1830          1840          1850          1860          1870          1880          1890          1900          1910          1920          1930          1940          1950          1960          1970          1980          1990          2000          2010          2020          2030          2040          2050          2060          2070          2080          2090          2100          2110          2120          2130          2140          2150          2160          2170          2180          2190          2200          2210          2220          2230          2240          2250          2260          2270          2280          2290          2300          2310          2320          2330          2340          2350          2360          2370          2380          2390          2400          2410          2420          2430          2440          2450          2460          2470          2480          2490          2500          2510          2520          2530          2540          2550          2560          2570          2580          2590          2600          2610          2620          2630          2640          2650          2660          2670          2680          2690          2700          2710          2720          2730          2740          2750          2760          2770          2780          2790          2800          2810          2820          2830          2840          2850          2860          2870          2880          2890          2900          2910          2920          2930          2940          2950          2960          2970          2980          2990          \"}}</script>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/javascript": [
       "$.getScript(\"files/js/WaveDrom.js\", function () {\n",
       "$.getScript(\"files/js/WaveDromSkin.js\", function () {\n",
       "WaveDrom.ProcessAll();});\n",
       "});\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "tr_buf.display()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.4.3+"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}
